<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Dojo_Data: dojo.data Envelopes - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.dojo.data.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.dojo.data.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dojo.view.html">Dojo View Helpers</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.dojo.data" class="section"><div class="info"><h1 class="title">Zend_Dojo_Data: dojo.data Envelopes</h1></div>
    

    <p class="para">
        Dojo provides data abstractions for data-enabled widgets via its
        <strong class="command">dojo.data</strong> component. This component provides the ability to attach a
        data store, provide some metadata regarding the identity field and
        optionally a label field, and an <acronym class="acronym">API</acronym> for querying, sorting, and
        retrieving records and sets of records from the datastore.
    </p>

    <p class="para">
        <strong class="command">dojo.data</strong> is often used with XmlHttpRequest to pull dynamic data from
        the server. The primary mechanism for this is to extend the
        QueryReadStore to point at a <acronym class="acronym">URL</acronym> and specify the query information. The
        server side then returns data in the following <acronym class="acronym">JSON</acronym> format:
    </p>

    <pre class="programlisting brush: javascript">
{
    identifier: &#039;&lt;name&gt;&#039;,
    &lt;label: &#039;&lt;label&gt;&#039;,&gt;
    items: [
        { name: &#039;...&#039;, label: &#039;...&#039;, someKey: &#039;...&#039; },
        ...
    ]
}
</pre>


    <p class="para">
        <span class="classname">Zend_Dojo_Data</span> provides a simple interface for building
        such structures programmatically, interacting with them, and serializing
        them to an array or <acronym class="acronym">JSON</acronym>.
    </p>

    <div class="section" id="zend.dojo.data.usage"><div class="info"><h1 class="title">Zend_Dojo_Data Usage</h1></div>
        

        <p class="para">
            At its simplest, <strong class="command">dojo.data</strong> requires that you provide the name of the
            identifier field in each item, and a set of items (data). You
            can either pass these in via the constructor, or via mutators:
        </p>

        <div class="example" id="zend.dojo.data.usage.constructor"><div class="info"><p><b>Example #1 Zend_Dojo_Data initialization via constructor</b></p></div>
            

            <pre class="programlisting brush: php">
$data = new Zend_Dojo_Data(&#039;id&#039;, $items);
</pre>

        </div>

        <div class="example" id="zend.dojo.data.usage.mutators"><div class="info"><p><b>Example #2 Zend_Dojo_Data initialization via mutators</b></p></div>
            

            <pre class="programlisting brush: php">
$data = new Zend_Dojo_Data();
$data-&gt;setIdentifier(&#039;id&#039;)
     -&gt;addItems($items);
</pre>

        </div>

        <p class="para">
            You can also add a single item at a time, or append items, using
             <span class="methodname">addItem()</span> and  <span class="methodname">addItems()</span>.
        </p>

        <div class="example" id="zend.dojo.data.usage.append"><div class="info"><p><b>Example #3 Appending data to Zend_Dojo_Data</b></p></div>
            

            <pre class="programlisting brush: php">
$data = new Zend_Dojo_Data($identifier, $items);
$data-&gt;addItem($someItem);

$data-&gt;addItems($someMoreItems);
</pre>

        </div>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Always use an identifier!</b><br /></span>
            

            <p class="para">
                Every <strong class="command">dojo.data</strong> datastore requires that the identifier column
                be provided as metadata, including <span class="classname">Zend_Dojo_Data</span>. In fact,
                if you attempt to add items without an identifier, it will raise an exception.
            </p>
        </p></blockquote>

        <p class="para">
            Individual items may be one of the following:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para">Associative arrays</p></li>

            <li class="listitem">
                <p class="para">Objects implementing a  <span class="methodname">toArray()</span> method</p>
            </li>

            <li class="listitem">
                <p class="para">
                    Any other objects (will serialize via
                     <span class="methodname">get_object_vars()</span>)
                </p>
            </li>
        </ul>

        <p class="para">
            You can attach collections of the above items via
             <span class="methodname">addItems()</span> or  <span class="methodname">setItems()</span> (overwrites
            all previously set items); when doing so, you may pass a single argument:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para">Arrays</p></li>

            <li class="listitem">
                <p class="para">
                    Objects implementing the <span class="classname">Traversable</span> interface
                    ,which includes the interfaces <span class="classname">Iterator</span> and
                    <span class="classname">ArrayAccess</span>.
                </p>
            </li>
        </ul>

        <p class="para">
            If you want to specify a field that will act as a label for the
            item, call  <span class="methodname">setLabel()</span>:
        </p>

        <div class="example" id="zend.dojo.data.usage.label"><div class="info"><p><b>Example #4 Specifying a label field in Zend_Dojo_Data</b></p></div>
            

            <pre class="programlisting brush: php">
$data-&gt;setLabel(&#039;name&#039;);
</pre>

        </div>

        <p class="para">
            Finally, you can also load a <span class="classname">Zend_Dojo_Data</span> item from a
            <strong class="command">dojo.data</strong> <acronym class="acronym">JSON</acronym> array, using the
             <span class="methodname">fromJson()</span> method.
        </p>

        <div class="example" id="zend.dojo.data.usage.populate"><div class="info"><p><b>Example #5 Populating Zend_Dojo_Data from JSON</b></p></div>
            

            <pre class="programlisting brush: php">
$data-&gt;fromJson($json);
</pre>

        </div>
    </div>

    <div class="section" id="zend.dojo.data.metadata"><div class="info"><h1 class="title">Adding metadata to your containers</h1></div>
        

        <p class="para">
            Some Dojo components require additional metadata along with
            the <strong class="command">dojo.data</strong> payload. As an example,
            <strong class="command">dojox.grid.Grid</strong> can pull data dynamically from a
            <strong class="command">dojox.data.QueryReadStore</strong>. For pagination to work
            correctly, each return payload should contain a <span class="property">numRows</span>
            key with the total number of rows that could be returned by the
            query. With this data, the grid knows when to continue making small
            requests to the server for subsets of data and when to stop
            making more requests (i.e., it has reached the last page of data).
            This technique is useful for serving large sets of data in your
            grids without loading the entire set at once.
        </p>

        <p class="para">
            <span class="classname">Zend_Dojo_Data</span> allows assigning metadata properties as
            to the object. The following illustrates usage:
        </p>

        <pre class="programlisting brush: php">
// Set the &quot;numRows&quot; to 100
$data-&gt;setMetadata(&#039;numRows&#039;, 100);

// Set several items at once:
$data-&gt;setMetadata(array(
    &#039;numRows&#039; =&gt; 100,
    &#039;sort&#039;    =&gt; &#039;name&#039;,
));

// Inspect a single metadata value:
$numRows = $data-&gt;getMetadata(&#039;numRows&#039;);

// Inspect all metadata:
$metadata = $data-&gt;getMetadata();

// Remove a metadata item:
$data-&gt;clearMetadata(&#039;numRows&#039;);

// Remove all metadata:
$data-&gt;clearMetadata();
</pre>

    </div>

    <div class="section" id="zend.dojo.data.advanced"><div class="info"><h1 class="title">Advanced Use Cases</h1></div>
        

        <p class="para">
            Besides acting as a serializable data container,
            <span class="classname">Zend_Dojo_Data</span> also provides the ability to manipulate
            and traverse the data in a variety of ways.
        </p>

        <p class="para">
            <span class="classname">Zend_Dojo_Data</span> implements the interfaces
            <span class="classname">ArrayAccess</span>, <span class="classname">Iterator</span>, and
            <span class="classname">Countable</span>. You can therefore use the data
            collection almost as if it were an array.
        </p>

        <p class="para">
            All items are referenced by the identifier field. Since identifiers
            must be unique, you can use the values of this field to pull
            individual records. There are two ways to do this: with the
             <span class="methodname">getItem()</span> method, or via array notation.
        </p>

        <pre class="programlisting brush: php">
// Using getItem():
$item = $data-&gt;getItem(&#039;foo&#039;);

// Or use array notation:
$item = $data[&#039;foo&#039;];
</pre>


        <p class="para">
            If you know the identifier, you can use it to retrieve an item,
            update it, delete it, create it, or test for it:
        </p>

        <pre class="programlisting brush: php">
// Update or create an item:
$data[&#039;foo&#039;] = array(&#039;title&#039; =&gt; &#039;Foo&#039;, &#039;email&#039; =&gt; &#039;foo@foo.com&#039;);

// Delete an item:
unset($data[&#039;foo&#039;]);

// Test for an item:
if (isset($data[foo])) {
}
</pre>


        <p class="para">
            You can loop over all items as well. Internally, all items are
            stored as arrays.
        </p>

        <pre class="programlisting brush: php">
foreach ($data as $item) {
    echo $item[&#039;title&#039;] . &#039;: &#039; . $item[&#039;description&#039;] . &quot;\n&quot;;
}
</pre>


        <p class="para">
            Or even count to see how many items you have:
        </p>

        <pre class="programlisting brush: php">
echo count($data), &quot; items found!&quot;;
</pre>


        <p class="para">
            Finally, as the class implements  <span class="methodname">__toString()</span>, you can
            also cast it to <acronym class="acronym">JSON</acronym> simply by echoing it or casting to string:
        </p>

        <pre class="programlisting brush: php">
echo $data; // echo as JSON string

$json = (string) $data; // cast to string == cast to JSON
</pre>


        <div class="section" id="zend.dojo.data.advanced.methods"><div class="info"><h1 class="title">Available Methods</h1></div>
            

            <p class="para">
                Besides the methods necessary for implementing the interfaces
                listed above, the following methods are available.
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setItems($items)</span>: set multiple items at once,
                        overwriting any items that were previously set in the
                        object. <var class="varname">$items</var> should be an array or a
                        <span class="classname">Traversable</span> object.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setItem($item, $id = null)</span>: set an individual
                        item, optionally passing an explicit identifier. Overwrites
                        the item if it is already in the collection. Valid items
                        include associative arrays, objects implementing
                         <span class="methodname">toArray()</span>, or any object with public properties.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">addItem($item, $id = null)</span>: add an individual
                        item, optionally passing an explicit identifier. Will raise
                        an exception if the item already exists in the collection.
                        Valid items include associative arrays, objects implementing
                         <span class="methodname">toArray()</span>, or any object with public properties.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">addItems($items)</span>: add multiple items at once,
                        appending them to any current items. Will raise an exception
                        if any of the new items have an identifier matching an
                        identifier already in the collection. <var class="varname">$items</var>
                        should be an array or a <span class="classname">Traversable</span> object.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getItems()</span>: retrieve all items as an array of
                        arrays.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">hasItem($id)</span>: determine whether an item with
                        the given identifier exists in the collection.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getItem($id)</span>: retrieve an item with the given
                        identifier from the collection; the item returned will be an associative
                        array. If no item matches, a <b><tt>NULL</tt></b> value is returned.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">removeItem($id)</span>: remove an item with the given
                        identifier from the collection.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">clearItems()</span>: remove all items from the collection.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setIdentifier($identifier)</span>: set the name of the
                        field that represents the unique identifier for each item in
                        the collection.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getIdentifier()</span>: retrieve the name of the
                        identifier field.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setLabel($label)</span>: set the name of a field
                        to be used as a display label for an item.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getLabel()</span>: retrieve the label field name.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">toArray()</span>: cast the object to an array. At a
                        minimum, the array will contain the keys &#039;identifier&#039;,
                        &#039;items&#039;, and &#039;label&#039; if a label field has been set in the object.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">toJson()</span>: cast the object to a
                        <acronym class="acronym">JSON</acronym> representation.
                    </p>
                </li>
            </ul>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dojo.view.html">Dojo View Helpers</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.dojo.html">Zend_Dojo</a></li>
  <li><a href="zend.dojo.introduction.html">Introduction</a></li>
  <li class="active"><a href="zend.dojo.data.html">Zend_Dojo_Data: dojo.data Envelopes</a></li>
  <li><a href="zend.dojo.view.html">Dojo View Helpers</a></li>
  <li><a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a></li>
  <li><a href="zend.dojo.build-layers.html">Zend_Dojo build layer support</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>